// Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of dart.core;

/**
 * 用于高效地串联字符串。
 *
 * 允许使用write*()方法增加构建字符串。
 * 只有当[toString]被调用时，所有字符串才会被串联成单一的字符串。
 */
class StringBuffer implements StringSink {

  /** 使用初始化内容创建字符串缓冲区。 */
  external StringBuffer([Object content = ""]);

  /**
   * 返回到目前为止积存的内容的长度。
   * 这是一个固定时间的操作。
   */
  external int get length;

  /** 返回缓冲区是否为空。这是一个固定时间的操作。 */
  bool get isEmpty => length == 0;

  /**
   * 返回缓冲区是否不为空。这是一个固定时间的操作。
   */
  bool get isNotEmpty => !isEmpty;

  /// 将[obj]转换成字符串，添加到缓冲区中。
  external void write(Object obj);

  /// 将[charCode]表示的字符串添加到缓冲区中。
  external void writeCharCode(int charCode);

  external void writeAll(Iterable objects, [String separator = ""]);

  external void writeln([Object obj = ""]);

  /**
   * 清空字符串缓冲区。
   */
  external void clear();

  /// 将串联的字符串作为缓冲区的内容返回。
  external String toString();
}
